/*
   Copyright 2009 Abdulla Abdurakhmanov (abdulla@latestbit.com)
   Original sources are available at www.latestbit.com

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
*/

package org.latestbit.smartobjects.network;

import java.io.IOException;
import java.nio.ByteBuffer;

/**
 * Interface provides access to all common method for managed connection 
 * @author abdulla-a
 *
 */
public interface IManagedConnection {
	
	/**
	 * Checks availability status
	 * @return true - if available to communicate, else false
	 */
	public boolean isOpen();
	
	/**
	 * Stops communication channel
	 */
	public void stop();	
	
	/**
	 * Gets endpoint location/configuration
	 * @return endpoint location
	 */
	public IEndpointLocation getEndpointLocation();

	/**
	 * Gets network connection to send 
	 * @return connection handler
	 * @throws IOException
	 */
	public ConnectionHandler getConnectionHandlerToSend() throws IOException;
	
	/**
	 * Sends raw data to network connection
	 * @param handler connection handler
	 * @param buffer input buffer with raw data
	 * @throws IOException
	 */
	public void send(ConnectionHandler handler, ByteBuffer buffer) throws IOException;

	/**
	 * Adds managed connection events listener
	 * @param listener managed connection events listener
	 */
	public void addConnectionListener(IManagedConnectionListener listener);
	
	/**
	 * Deletes managed connection events listener
	 * @param listener managed connection events listener
	 */
	public void delConnectionListener(IManagedConnectionListener listener);

	/**
	 * Adds managed connection stream events listener
	 * @param listener managed connection stream events listener
	 */
	public void addStreamListener(IManagedStreamListener listener);
	
	/**
	 * Deletes managed connection stream events listener
	 * @param listener managed connection stream events listener
	 */
	public void delStreamListener(IManagedStreamListener listener);
	
	/**
	 * Associates/assigns network connection handler with this managed connection. 
	 * This method provided for coordinator implementations.
	 * @param handler network connection handler
	 */
	public void assignConnectionHandler(ConnectionHandler handler);

	/**
	 * Unassociates/unassigns network connection handler with this managed connection. 
	 * This method provided for coordinator implementations.
	 * @param handler network connection handler
	 */	
	public void unassignConnectionHandler(ConnectionHandler handler);

	/**
	 * Gets coordinator context linked with managed connection
	 * @return coordinator context
	 */
	public ICoordinatorContext getCoordinatorContext();
	
	/**
	 * Sets a new instance of coordinator context for this managed connection
	 * @param context coordinator context
	 */
	public void setCoordinatorContext(ICoordinatorContext context);
}
